What is @jridgewell/gen-mapping?
The @jridgewell/gen-mapping package is a library for generating source maps, which are used to map the transformed source to the original source, enabling developers to debug their code more easily after it has been compiled or minified. It provides a simple API for adding mappings and generating the source map.
What are @jridgewell/gen-mapping's main functionalities?
Creating a new source map generator
This feature allows you to create a new source map generator instance, specifying the output file name for the source map.
{"const { GenMapping } = require('@jridgewell/gen-mapping');
const map = new GenMapping({
file: 'minified.js'
});
}
Adding mappings to the source map
This feature allows you to add individual mappings to the source map, linking a location in the generated file to a location in the original source file.
{"const { addMapping } = require('@jridgewell/gen-mapping');
addMapping(map, {
generated: { line: 1, column: 5 },
source: 'original.js',
original: { line: 1, column: 30 }
});
}
Generating the source map
This feature generates the final source map from the added mappings, which can then be used by browsers or other tools to map the transformed source back to the original source.
{"const { toMapping } = require('@jridgewell/gen-mapping');
const sourceMap = toMapping(map);
}
Other packages similar to @jridgewell/gen-mapping
source-map
The 'source-map' package provides similar functionality for generating source maps. It offers a more comprehensive API for manipulating source maps, including parsing and merging existing source maps, which @jridgewell/gen-mapping does not provide.
source-map-js
The 'source-map-js' package is a fork of the 'source-map' library that focuses on performance improvements and bug fixes. It is similar to @jridgewell/gen-mapping in that it generates source maps, but it also includes features for parsing and manipulating source maps.
magic-string
The 'magic-string' package is designed for manipulating strings and generating source maps in the process. It is different from @jridgewell/gen-mapping in that it provides a higher-level API for string manipulation, which includes source map generation as a byproduct of those manipulations.
@jridgewell/gen-mapping
Generate source maps
gen-mapping
allows you to generate a source map during transpilation or minification.
With a source map, you're able to trace the original location in the source file, either in Chrome's
DevTools or using a library like @jridgewell/trace-mapping
.
You may already be familiar with the source-map
package's SourceMapGenerator
. This
provides the same addMapping
and setSourceContent
API.
Installation
npm install @jridgewell/gen-mapping
Usage
import { GenMapping, addMapping, setSourceContent, encodedMap } from '@jridgewell/gen-mapping';
const map = new GenMapping({
file: 'output.js',
sourceRoot: 'https://example.com/',
});
setSourceContent(map, 'input.js', `function foo() {}`);
addMapping(map, {
generated: { line: 1, column: 0 },
source: 'input.js',
original: { line: 1, column: 0 },
});
addMapping(map, {
generated: { line: 1, column: 9 },
source: 'input.js',
original: { line: 1, column: 9 },
name: 'foo',
});
assert.deepEqual(encodedMap(map), {
version: 3,
file: 'output.js',
names: ['foo'],
sourceRoot: 'https://example.com/',
sources: ['input.js'],
sourcesContent: ['function foo() {}'],
mappings: 'AAAA,SAASA',
});
Benchmarks
node v18.0.0
amp.js.map
gen-mapping: addSegment x 462 ops/sec ±1.53% (91 runs sampled)
gen-mapping: addMapping x 471 ops/sec ±0.77% (93 runs sampled)
source-map-js: addMapping x 178 ops/sec ±1.14% (84 runs sampled)
source-map-0.6.1: addMapping x 178 ops/sec ±1.21% (84 runs sampled)
source-map-0.8.0: addMapping x 177 ops/sec ±1.21% (83 runs sampled)
Fastest is gen-mapping: addMapping,gen-mapping: addSegment
gen-mapping: decoded output x 157,499,812 ops/sec ±0.25% (100 runs sampled)
gen-mapping: encoded output x 625 ops/sec ±1.95% (88 runs sampled)
source-map-js: encoded output x 162 ops/sec ±0.37% (84 runs sampled)
source-map-0.6.1: encoded output x 161 ops/sec ±0.51% (84 runs sampled)
source-map-0.8.0: encoded output x 191 ops/sec ±0.12% (90 runs sampled)
Fastest is gen-mapping: decoded output
***
babel.min.js.map
gen-mapping: addSegment x 35.38 ops/sec ±4.48% (48 runs sampled)
gen-mapping: addMapping x 29.93 ops/sec ±5.03% (55 runs sampled)
source-map-js: addMapping x 22.19 ops/sec ±3.39% (41 runs sampled)
source-map-0.6.1: addMapping x 22.57 ops/sec ±2.90% (41 runs sampled)
source-map-0.8.0: addMapping x 22.73 ops/sec ±2.84% (41 runs sampled)
Fastest is gen-mapping: addSegment
gen-mapping: decoded output x 157,767,591 ops/sec ±0.10% (99 runs sampled)
gen-mapping: encoded output x 97.06 ops/sec ±1.69% (73 runs sampled)
source-map-js: encoded output x 17.51 ops/sec ±2.27% (37 runs sampled)
source-map-0.6.1: encoded output x 17.40 ops/sec ±4.61% (35 runs sampled)
source-map-0.8.0: encoded output x 17.83 ops/sec ±4.85% (36 runs sampled)
Fastest is gen-mapping: decoded output
***
preact.js.map
gen-mapping: addSegment x 13,516 ops/sec ±0.27% (98 runs sampled)
gen-mapping: addMapping x 12,117 ops/sec ±0.25% (97 runs sampled)
source-map-js: addMapping x 4,285 ops/sec ±1.53% (98 runs sampled)
source-map-0.6.1: addMapping x 4,482 ops/sec ±0.20% (100 runs sampled)
source-map-0.8.0: addMapping x 4,482 ops/sec ±0.28% (99 runs sampled)
Fastest is gen-mapping: addSegment
gen-mapping: decoded output x 157,769,691 ops/sec ±0.06% (92 runs sampled)
gen-mapping: encoded output x 18,610 ops/sec ±1.03% (93 runs sampled)
source-map-js: encoded output x 5,397 ops/sec ±0.38% (97 runs sampled)
source-map-0.6.1: encoded output x 5,422 ops/sec ±0.16% (100 runs sampled)
source-map-0.8.0: encoded output x 5,595 ops/sec ±0.11% (100 runs sampled)
Fastest is gen-mapping: decoded output
***
react.js.map
gen-mapping: addSegment x 5,058 ops/sec ±0.27% (100 runs sampled)
gen-mapping: addMapping x 4,352 ops/sec ±0.13% (97 runs sampled)
source-map-js: addMapping x 1,569 ops/sec ±0.19% (99 runs sampled)
source-map-0.6.1: addMapping x 1,550 ops/sec ±0.31% (97 runs sampled)
source-map-0.8.0: addMapping x 1,560 ops/sec ±0.18% (99 runs sampled)
Fastest is gen-mapping: addSegment
gen-mapping: decoded output x 157,479,701 ops/sec ±0.14% (99 runs sampled)
gen-mapping: encoded output x 6,392 ops/sec ±1.03% (94 runs sampled)
source-map-js: encoded output x 2,213 ops/sec ±0.36% (99 runs sampled)
source-map-0.6.1: encoded output x 2,238 ops/sec ±0.23% (100 runs sampled)
source-map-0.8.0: encoded output x 2,304 ops/sec ±0.20% (100 runs sampled)
Fastest is gen-mapping: decoded output